BBS in a Box 3/BBS in a box - Trilogy III.iso/Files/System7 tools/S/System 7 corner/HyperCard 2.1

Text File | 1991-06-25 | 24.6 KB | 646 lines | [TEXT/PCXT]

Here are the known incompatibilities between HyperCard 2.0v2 and System 7.0.
They have all been fixed in HyperCard 2.1.

- When you ask for the names of the system Help or Application menus from
  HyperTalk, you get indecipherable strings.
- "the menus" doesn't include the system Help and Application menus.
- When you launch HyperCard and it can't find the Home stack, you must
  select a Home stack from a standard file dialog.  If the stack you
  select can't be opened (this can happen if it has already been opened
  with write permission by another application) HyperCard will freeze
  the machine.
- If there are no user menus, the System 7 Help menu disappears when the
  userLevel changes.  It comes back if a user menu is created from a script.
- The HyperTalk commands that refer to files don't work with alias files.



When HyperCard 2.1 receives an Apple event, it sends an appleEvent
message to the current card.  That means that you can respond to Apple
events with HyperTalk scripts.  But before you try to write such scripts,
there are some terms and conventions you should be familiar with.

The figure
----------

Apple events are like a package full of raw materials that arrive at a
factory.  They have a return address on them -- in HyperTalk, a string of
the form "Zone:Macintosh:Program".  They have an explanation of what their
contents are for -- the class and id, which together consititute a verb,
directing the receiver what do to with the package.  And of course there
are the contents themselves -- the event parameters.

When you get one of these packages, you have to unpack it before you can
make something out of the raw materials inside.  But you can't just rip
into the package willy-nilly.  You have to ask for what you want, by name.
"Give me the snod." "OK, now give me the lerd."  You unpack the contents,
one by one, and make out of them whatever you're directed to make by the
class and id.

The catch is that the package doesn't come with a packing list.  You're
supposed to know what's in it -- you have a big book that tells you that
whenever you get a package that you're supposed to make into a "wild plum",
it's supposed to have a "bork", a "flam", and a "nitz" inside of it.  So
you unpack the bork, the flam, and the nitz, and then you make the wild
plum out of them and send it back.

    Apple event = package
    class and id = terse directions for what to do with the package
    parameters = contents of the package
    keywords = names for each thing in the package


The lesson
----------

In HyperTalk, when you handle the appleEvent message, you first look at
the class and id, and they tell you what you're supposed to do with the
event.  If it's an event that you know how to handle, you already know what
the parameters are -- you've agreed with the sender in advance on what's
supposed to be in it, or it's a standard Apple event defined in the
voluminous standard documentation.  So you unpack the parameters with the
"request" command, manipulate them, and send back what you made out of them
with the "reply" command.

The script might look like this:

   on appleEvent class,id,sender
     if class & id is "wildplum" then
       request ae data with keyword "bork"
       if the result is not empty then   -- probably "Not found"
         reply error "Expected a bork but got none."
         exit appleEvent
       end if
       put it into theBork
       request ae data with keyword "flam"
       .
       .
       .
       .
       get wildPlumMakingFunction(theBork,theFlam,theNitz)  -- process it
       reply it  -- send back the reply
     else pass appleEvent  -- we don't recognize this event; pass it on
   end appleEvent


Keywords
--------

Think of a keyword for a piece of data in the package as its name -- it's
the handle you need to pull it out of the package.  Asking for a parameter
by keyword is the same as asking for a piece of raw material by name.

Keywords are arbitrary.  Whoever invents an Apple event makes them up, on
the spot, out of the blue, to name the pieces of data that go along with
the event.  The standard Apple events that have already been defined, along
with the keywords for their required and optional parameters, are described
in the Apple Event Registry.


The direct object
-----------------

Many Apple events arrive with just one piece of raw material in them, or
one piece that's more important than the others.  By convention, this piece
is given the keyword "----" and is referred to in the Apple event
documenation as "the direct object" or "the direct parameter".  These are
pretty ugly names, so in HyperTalk you can just call it the "data" and
leave off the keyword specification -- HyperCard will know what you're
talking about.

   request appleEvent data

This is equivalent to the following statement.

   request appleEvent data of keyword "----"

The direct object for the 'odoc' event is the list of documents to open.
The direct object for the 'dosc' event is the script to execute.  And so
on.


Event attributes
----------------

Apple events come along with more than just an address, a verb, and pieces
of data.  They also come with modifiers, or "attributes", which you can
think of as "special handling instructions".  The class, id, and sender are
all attributes also, but HyperCard gives you these automatically as
parameters to the appleEvent message.  The timeout value, the transaction
id, and the return id -- the identifier you put on the reply so that the
sender knows, when his wild plum arrives, which package you made it out of
-- are additional attributes.  If you need to look at these, the "request"
command will let you.

You can get the return id,

   request appleEvent return id
   request appleEvent data of keyword "rtid"  -- same thing, only uglier

the timeout value,

   request appleEvent data of keyword "timo"

the transaction id,

   request appleEvent data of keyword "tran"

and whatever else you think you need, as long as you know its keyword.  We
have special forms of the request command for the class, id, sender, direct
object, and return id -- for everything else, you have to tell HyperCard
what you want by keyword.

   request appleEvent class   -- gives you the class attribute
   request appleEvent id      -- gives you the id attribute
   request appleEvent sender  -- gives you the sender attribute
   request appleEvent data    -- gives you the direct object parameter
   request appleEvent return id   -- gives you the return id attribute


Kevin Calhoun
[e-mail]

***********

HyperCard 2.1 Release Notes for Developers
Date: 23 May 91 22:50:05 GMT
Organization: Apple Computer Inc, Cupertino, CA


HyperCard 2.1 Release Notes


Overview of this Release
------------------------

HyperCard 2.1 is the version of HyperCard recommended for use with System 7.0.
It is also compatible with System 6.0.5 and System 6.0.7.


Revisions for Support of System 7.0 Features
--------------------------------------------

These revisions are grouped by their associated Toolbox Manager.


Alias Manager

    When the Alias Manager is present, HyperCard 2.1 will call it to resolve
alias files.  Therefore, the following commands will work properly with alias
files.

    go to stack <alias file>
    open <alias file> with <alias file>
    open file <alias file>
    write to file <alias file>
    read from file <alias file>
    picture <alias file>

    The XCMD callback GetFilePath will also resolve alias files. Therefore,
XCMDs that use this callback to locate files will require no revision to work
with alias files.  (The Picture XCMD is an example.)

    In addition, if HyperCard finds an alias file when looking for the Home
stack on startup, the alias file will be resolved.


Apple Event Manager

    When the AppleEvent Manager is present, HyperCard 2.1 will use it to process
and send Apple events.  HyperCard will recognize and handle the standard Apple
events for opening documents, printing documents, quitting, executing a script,
and evaluating an expression.

    In addition, several of HyperTalk's built-in commands will have the added
ability to send specific Apple events to other applications.

    Event class  Event ID       Related HyperTalk command
    -----------  --------       -------------------------
    'aevt'       'oapp'         open <application>
    'aevt'       'odoc'         open <document> with <application>
    'aevt'       'pdoc'         print <document> with <application>
    'aevt'       'quit'         close <application>
    'aevt'       'clos'         close <document> with <application>
    'misc'       'dosc'         send <expr> to program <programExpr>
    'misc'       'eval'         request <expr> of program <programExpr>

    If you want to launch another application or open a document with another
application, use the HyperTalk command "open".  If you want to print a document
with another application, use the command "print".  If you want to close a
document in another application or quit another application, use the command
"close".  If you want to execute a script or macro in another application, use
the HyperTalk command "send".  If you want to evaluate an expression in another
application, use the command "request".

    Please note that among these Apple events, only 'oapp', 'odoc', 'pdoc', and
'quit' are universally supported.  All other Apple events that HyperCard can
send will be effective only if the target application includes specific support
for them. For example,

    close "My Expense Report" with "FabCalc"

will work properly only if the application FabCalc supports the 'clos' Apple
event.

    The "open", "print", and "close" commands will work only with applications
that reside on the same machine as HyperCard.  The "send" and "request" commands
will work with any linkable program running on the network. See "Determining the
Target Program", below.

Sending scripts to other programs

    The send command in HyperTalk will send a "do script" Apple event from
HyperCard to another application running remotely.  It can be used to send a
script to any program that understands the standard 'dosc' Apple event. By
default, HyperCard waits for a reply from the target program before continuing.
However, you can specify that you don't want to wait for a reply.

    Examples:

    send "make waves" to program "De Anza 6/2nd:WildCraft:HyperCard"
    send "build {project}" to program "MPW Shell" without reply

Evaluating expressions in other programs

    The request command in HyperTalk will send an "evaluate expression" Apple
event from HyperCard to another application running remotely.  It can be used to
send an expression to any program that understands the standard 'eval' Apple
event.  The value of the expression will be put into the local variable "it".

    Examples:

    request "the name of this stack" of program "HyperCard"
    request "{target}" from program "MPW Shell"

Handling failures

    The "send", "open", "print", "close", and "request" commands set "the
result" as follows when they fail.

Condition                               the result
---------                               ---------------
User canceled the "Link to program"     "Cancel"
  dialog.
Target program didn't handle event.     "Not handled by target program"
Target program timed out.               "Timeout"
Target program returned error string    the string
  in reply.
Target program returned error number    "Got error <errorNum>
  in reply, or AESend returned some       when sending Apple( event"
  other error.

Establishing program links

    When sending Apple events to another program, if HyperCard has not
established a link with the target program, the user will be presented with a
dialog, through which the link will be established.  If a link has already been
established between HyperCard and the target program, the Apple event will be
sent without further user interaction.

Determining the target program

    The target program for Apple events is specified by a string in the
following format:

    zone:machine:program

    Examples:

    "Fifth Floor:Gizmo:MacWrite"
    "Baby mac:MacWrite"
        -- zone omitted; HyperCard assumes same zone
    MacWrite
        -- zone and machine omitted; HyperCard assumes same zone,
            same machine

    HyperCard's address on the network is contained in the property, "the
address".

    You can use the itemDelimiter property to parse program addresses. For
example, given a string that specifies a target program, the following HyperTalk
function will return the name of the program if you send it a colon as the
delimiter and the string as the text.

    function lastHCItem delim,theText
      put the itemDelimiter into savedDelimiter
      set the itemDelimiter to delim
      put the last item of theText into lastItem
      set the itemDelimiter to savedDelimiter
      return lastItem
    end lastHCItem

Choosing a target program

    The answer command has been extended for use with the Program Linking
dialog, so that scripters can allow users to select a program to link to.

    answer program prompt { of type <factorList> }

When used in this way, the answer command displays the PPC browser, from which
the user can select any program running on any machine connected to the
AppleTalk network.  A string representing the program the user selects is placed
into the local variable "it".

Examples:

    answer program "Where did you say that program was again?"
    answer program "Choose a spelling checker:" of type "Spellcheck"

    In addition,  a scripter can determine which programs are running on the
same machine as HyperCard by examining the new HyperTalk function, "the
programs".  It returns a return-delimited list of all the linkable programs
currently running on the same machine as HyperCard.

Handling Apple events

    When HyperCard receives an Apple event, it will send a new HyperTalk system
message, "appleEvent", to the current card, along with parameters that enable a
script to determine the class, id, and the sender of the Apple event.  For
example, when the Finder sends HyperCard an Apple event of class 'aevt' and id
'odoc', HyperCard sends the HyperTalk message "appleEvent aevt,odoc,Finder" to
the current card.

    A script that handles an appleEvent message can gather the parameters of the
Apple event by using the new HyperTalk command "request".

    request appleEvent data { [ of | with ] keyword <expr> }

This command puts the parameter or attribute with the specified keyword into the
local variable "it".  For example, you can obtain a parameter of keyword "errs",
the standard Apple event keyword for an error string, as follows:

    request appleEvent data with keyword "errs"
    put it into errorString

If there is no attribute or parameter with the keyword you specify, HyperCard
sets the result to "Not found".

    If you don't supply a keyword, HyperCard assumes you're requesting the
direct object of the Apple event, which is defined by the Apple event manager as
the parameter with keyword "----".  The request command also supports several
special cases for important attributes of Apple events:

    request appleEvent class
    request appleEvent id
    request appleEvent sender
    request appleEvent return id

    HyperCard will attempt to convert all the Apple event parameters to strings,
for use in HyperTalk.  The Apple event manager automatically handles the
conversion of numerical forms to strings; HyperCard installs coercion handlers
for alias records, return ids, process serial numbers, target ids, class and id
types, and lists.

    If an incoming Apple event specifies that user action is not permissible,
the global property lockErrorDialogs will automatically be set to TRUE (see
"Error Handling", below).  The scripter can override this setting.

    Example:  a scripter defines an event of class 'WILD' and id 'cnvt' as a
request to convert a 1.2.5 stack to the 2.0 file format.  The direct object of
the Apple event is defined to be the pathname of the stack.  The following
script will do the trick.

    on appleEvent eventClass,eventID,sender
      if eventClass & eventID is not "WILDcnvt"
      then pass appleEvent
      else
        request appleEvent data
        if it is empty then exit appleEvent
        go to stack it
        if the result is not empty then exit appleEvent

        if there is a menuItem "Convert Stack..." in menu "File"
        then doMenu "Convert Stack..." without dialog
      end if
    end appleEvent

    Example:  when a stack is opened from the Finder while HyperCard is running,
HyperCard 2.1 will open the stack in a new window.  This behavior is different
from previous versions of HyperCard, which would go to the stack in the
currently active window.  If you prefer the old behavior, you can put the
following script in your Home stack.

    on appleEvent eventClass,eventID,sender
      if eventClass & eventID is not "aevtodoc"
      then pass appleEvent
      else
        request appleEvent data
        put line 1 of it into stackToOpen
        go to stack stackToOpen
      end if
    end appleEvent

    If HyperCard receives the appleEvent message, either because it was not
intercepted by a script or because it was passed to it by a script, HyperCard
will check whether the current Apple event is of the types it knows how to
respond to, and if so, will treat it appropriately.  HyperCard 2.1 will
recognize the following standard Apple events: 'odoc', 'pdoc', 'quit', 'dosc',
and 'eval'.

    HyperCard responds to the 'odoc' event by checking whether the specified
files are stacks and, if so, opening them, each in a new window.

    HyperCard responds to the 'pdoc' event by checking whether the specified
files are stacks and, if so, opening them one at a time in a new window,
printing them, and closing them again.

    HyperCard responds to the 'quit' event just as it would if "Quit HyperCard"
were chosen from the File menu.

    HyperCard responds to a 'dosc' event by compiling and executing the
HyperTalk statements sent to it as the direct object of the event.

    HyperCard responds to an 'eval' event by evaluating the expression sent to
it as the direct object of the event and putting the value into the direct
object of the reply.

Replying to Apple events

    Scripters can reply to Apple events from HyperTalk with a new command,
"reply".

    reply <expr> { with keyword <expr> }

If you don't specify a keyword for the reply parameter, the parameter will
become the direct parameter of the reply.  If you wish to return an error
string, you can use the following form of the reply command:

    reply error <expr>

This is equivalent to:

    reply <expr> with keyword "errs"

    The reply event is sent when the chain of execution is complete.

    For example, the following script will handle Apple events of class 'WILD'
and type 'defn' by searching for a string in a background field named "Glossary
Entry" and returning the contents of a background field named "Definition".

    on appleEvent eventClass,eventID,sender
      if eventClass is "WILD" and eventID is "defn" then
        request appleEvent data
        find it in field "Glossary Entry"
        if the result is empty  -- successful find
        then reply field "Definition"
        else reply error "Not found"
      else pass appleEvent
    end appleEvent

The "request" and "reply" commands set the result to "No current Apple( event."
when there is no current Apple event to handle.


Miscellaneous Revisions
-----------------------

Menus

    When you ask for the names of the Apple, Help, and Application menus from
HyperTalk, you get "Apple", "System Help", and "Application", respectively.

Error Handling

    In order to execute scripts without interaction with the user, as well as to
provide a better means for testing HyperCard's error messages, it's now possible
to lock error dialogs and to put HyperTalk into a "quiet mode" for script
execution.  When HyperTalk encounters an error while in "quiet mode", it aborts
execution of pending scripts just as it normally would, but instead of
displaying a dialog with an error message, it sends a "errorDialog" message to
the current card with the error message as its parameter.  This message
substitutes for the first "idle" message that would be sent in normal mode after
HyperTalk cleans up and HyperCard returns to its main event loop.

    Example:

    set lockErrorDialogs to TRUE  -- puts HyperTalk into "quiet mode"
    lock error dialogs  -- an alternate form
    unlock error dialogs

When HyperCard receives an Apple event for which the sender has specified that
no user interaction is allowed, it will automatically set lockErrorDialogs to
TRUE before handling the event.

Determining which version of System Software is running

    A new function has been added to HyperTalk, "the systemVersion".  It returns
the version of system software is running in a decimal string.  For example, it
will return 6.07 instead of 6.0.7, to allow scripters to use it with HyperTalk's
arithmetic operators.

Specifying Windows

    You can now refer to windows by number and by id as well as by name.
Therefore, the following commands are now valid.

    get the id of the card window
    set the loc of window 1 to 50,50
    hide last window

    Both the Picture and Palette XCMDs now send the id of a newly created window
as an additional parameter to its open message.  For example, after the Picture
XCMD creates a new window, it sends the following message to the current card:

    openPicture <name of window>,<id of window>

Read and Write

    The HyperTalk "read" and "write" commands have been enhanced.  The following
examples are now valid.

    read from file "Fred" at 100 for 12
    read from file "Fred" until end  -- 'eof' works too
    write myVar to file "Fred" at 200
    write moreStuff to file "Fred" at end  -- 'eof' works too

In addition, the 16K limit on the amount of text that could be read at once has
been removed.  If the amount of text you ask for won't fit in memory, HyperCard
sets the result to "Not enough memory to read from file."

Getting the internal modem for the Portable to work with "dial"

    A new global property, "the dialingTime", has been added, especially for
users of the internal modem for the Macintosh Portable.  It determines how long
HyperCard waits, in ticks, after sending the dial string, before closing the
serial connection with the modem.   The default is 180 (3 seconds).

Owners

    Windows and cards now have an "owner" property.  For windows, the owner is
determined as follows.

    Creator                   Owner
    ----------                ----------
    HyperCard                 "HyperCard"
    desk accessory or driver  "System"
    XCMD                      the name of the XCMD
    anything else             "Unknown"

    The owner of a card is the name of its background.

More Parameters Available

    The parameters for the "start", "stop", and "set" commands are now available
within overriding handlers.


Summary
-------

    New messages:  appleEvent, errorDialog
    New commands:  request, reply
    New functions:  programs(), systemVersion()
    New properties:  the address, the itemDelimiter, the lockErrorDialogs, the
dialingTime, the owner
    New constants:  comma, colon

    Enhanced commands: open, print, close, send, read, write, answer, lock,
unlock, set, start, stop


******

Subject: Properties for windows in HyperCard 2.1
Date: 21 May 91 00:02:10 GMT


In HyperCard 2.1, all windows have the following properties:

  loc      (or "location")
  visible
  name     (new for windows in 2.1)
  number   (new for windows in 2.1; given in front-to-back order)
  id       (new for windows in 2.1)
  owner    (new in 2.1)

Numbers and IDs for windows were added to make it possible for scripters to
distinguish between two windows with the same name.  Now that they've been
added, there are four ways to specify built-in windows.  For example:

   show the card window
   show window <the name of the card window>
   show window <the number of the card window>
   show window id <the id of the card window>

And there are three ways to specify all other windows -- by name, by number, and
by id.  All of the different ways of referring to windows are interchangeable.
You can use them with the commands get, set, send, close, hide, and show, with
the number function, and in property expressions.

In order to make the ID of a newly created Picture window available for use by
scripters, we've added a second parameter to the "openPicture" message -- the
window ID.  We've done the same thing for the Palette XCMD, which sends an
"openPalette" message when it creates a new window.

The owner property will be useful for people managing large numbers of windows.
It's "HyperCard" for any of HyperCard's built-in windows, "System" for windows
owned by desk accessories or drivers, the name of of the external that created
the window for external windows, and "Unknown" for everything else.

Kevin Calhoun
[e-mail]